Repository navigation
Kit v1.4.0: shared naming conventions, PPTX extractor, package and ZIP prunes - #3
Merged
Merged
Conversation
Four kinds of drift had accumulated across the five workshop repos, each one
locally reasonable and collectively confusing for a participant who attends more
than one workshop. Record the agreed convention in one place so a content repo
can point at it instead of restating or overriding it.
New "Shared Naming Conventions" section:
- The prerequisites page is titled `Prerequisites`, or `Prerequisites - <Step>`
where a workshop splits it. Was a three-way split between `Pre-reqs -`,
`Pre-req -` and `Prerequisites`.
- Every exercise page closes with one `## Success check` list. Was a mix of
`Success Criteria` plus a near-duplicate `Verification Checks`, `Success check`
and `Recap`. An up-front `Requirements` or `Objectives` section is unaffected.
- Participant placeholders use angle brackets: `<your-name>`, `<your-initials>`.
Was `[participant name]`, `<your-name>` and `{{your-initials}}`.
- `{{ }}` is reserved for `{{WORKSHOP_*}}` tokens, so nothing a participant
replaces by hand may use that shape. `{{your-initials}}` looked exactly like a
build-time token and silently was not one.
- `sidebar_position` runs contiguously from 1, and front matter `title` must
match the page `# H1`.
Also, under Workshop Configuration Variables: no delivery-specific literal
belongs in `docs/`. A tenant URL, org, join link, Studio Web template name,
cohort, city or date goes in `config/workshop-targets.json` and renders through
the WorkshopEnv components. Two repos had a city and a date baked into a template
name participants must search for, and one had a hardcoded tenant URL five lines
below the same value rendered from a variable.
And under Downloads And Assets:
- Serve participant files through `WorkshopDownloadLink`, never an external file
host. The IXP workshop linked two Google Drive files that could not be
versioned with the content.
- Name a download for what is inside it, not just the exercise number.
This needs a release and a repin before the fenced AGENTS.md regions in the
content repos pick it up.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two content repos each carried a copy of `scripts/extract-pptx-assets.py`, the tool that pulls screenshots, ordered text blocks and callout geometry out of a facilitator deck. The copies had diverged, and the older one was the broken one — exactly the drift the kit exists to stop. The IXP copy filtered on `shape.shape_type == MSO_SHAPE_TYPE.PICTURE`. An image dropped into a PowerPoint content placeholder is a `PlaceholderPicture`, whose shape_type is PLACEHOLDER, so it was skipped. On the Communications Mining deck that silently lost 18 of 33 screenshots, with no error and no non-zero exit. The CM copy had the three-line fix and a `callout_markers` pass the IXP copy lacked. Rather than port the fix to a second copy, the fixed version moves here and both per-repo copies go away. Generalised for sharing: - `page_for_slide` and `likely_role` were hardcoded to one deck's slide numbers and keywords. They are now an optional `--slide-map` JSON, so the code is shared while the deck-specific knowledge stays in the workshop that owns the deck. `schemas/pptx-slide-map.schema.json` documents the shape; slides are given as integers or inclusive `"N-M"` ranges, and role rules match on slide number, on case-insensitive text, or both, first rule winning. - Without a map every slide lands in one folder, which is the right first pass over an unfamiliar deck — you cannot write the slide-to-page table until you have seen what came out. The run reports how many slides landed there, because a map written against a stale deck revision otherwise looks like a success. `workshop-kit extract-pptx` wraps it. python-pptx and Pillow are deliberately not project dependencies — this is a one-off authoring step, not part of any build — so the wrapper probes for an interpreter (PYTHON, python3, python) and the two modules, and prints the pip line instead of a traceback. `doctor` now reports a leftover `scripts/extract-pptx-assets.py` alongside the other files a migrated repo should no longer have. Verified against a fixture deck built for the purpose: one pasted picture, one dropped into a content placeholder, and a numbered oval overlapping a third. All three extracted, including the placeholder one; pages routed by both range and keyword rules; the callout marker computed to 25.0%/25.0%, matching the geometry by hand. The missing-dependency path was checked too. CI gained an `ast.parse` check on the extractor, since no build step exercises it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`uip codedapp pack` writes a fresh timestamped `.uipath/<name>.<version>.nupkg` on every run and never removes one. Nothing else cleans them up either, so the directory grows without bound: coding-agents-workshop reached 147 MB across 21 files in two months. They are gitignored, so this shows up as disk use rather than as a diff, and nobody notices. After a successful pack, keep the newest 3 per package name and delete the rest, reporting what went and how much was freed. `UIPATH_CODEDAPP_KEEP` overrides; below 1 or non-numeric warns and falls back to 3. Per NAME, not per directory. That repo packs a different app name per training target — tc20260721-ca-workshop, ifca20260722-ca-workshop, growth-*, and so on. A global "keep the newest 3" would have kept three tc20260727-* files and deleted growth-coding-agents-workshop, the only package of its name. `publish` is a separate command that runs against the local file, so that breaks pack-now- publish-later. Grouping by name also guarantees the file the current run just produced survives, since it is the newest in its own group. Deliberately conservative about what it will touch: - The version is anchored as a trailing semver rather than assumed to start at the first dot, so a package name containing a dot still splits correctly. - Anything not matching `<name>.<semver>.nupkg` is left alone, `app.config.json` and `metadata.json` included. - Local packages are build artifacts, not the deliverable; publish has already uploaded to Orchestrator. Tested against a fixture replicating that repo's exact 21 files and mtimes: 21 -> 14 across six name groups, oldest of each group dropped, newest kept, single-file groups untouched, config files untouched, unparseable names untouched, KEEP=1 and KEEP=10 honoured, KEEP=0 and KEEP=abc rejected with a warning, and a missing `.uipath/` returning quietly. CI carries the case that matters — a name never packed again surviving while another name is pruned. `prunePackages` is exported and `main()` now runs only on direct execution, so the delete path can be exercised without spawning the whole deploy script. The module is always spawned as a script in production, so the guard is inert there. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The section said content repos "pin a caret range and rely on Dependabot to surface kit releases". Both halves are wrong, and the Releasing section directly above it already said the opposite. The whole workshop-kit approach depends on this being unambiguous, so a reader hitting the contradiction has no way to tell which one governs. Reality, checked against all five content repos: every one pins the exact tag `github:UiPath-LAB-TEC/workshop-kit#v1.3.0`, resolved through package-lock.json to a specific commit. There is no caret range anywhere. The caret-plus-registry model was considered and rejected — the workspace TODO records the decision as "public repo + git tag, no registry, no auth. Exact pins rather than semver ranges" — and this paragraph was left over from that draft. Rewritten around the fact everything else follows from: the version number is a signal, not a trigger. Dependabot cannot bump a `github:` tag (no registry to poll, no range to compare), `npm install` cannot either (the lockfile pins the previous tag's commit), and only `workshop-kit repin <tag>` moves a repo, run per repo on purpose. Each content repo's dependabot.yml already carries this in a comment, including that a kit group once sat there doing nothing. Also states the two consequences that were never written down: a major does not break every workshop the day it is tagged, only the next repo that repins — a delivered workshop can sit on an old tag indefinitely, which is the point. And the mirror image, that a shared fix is not live anywhere until each repo is repinned, so cross-repo CI proves a change is safe without delivering it. A new CLI command is added to the minor bullet, since two of them have now shipped as minors with the rule unstated. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A deleted downloads/<name>/ folder left its ZIP behind forever. That is not merely untidy. static/downloads/ is gitignored, so a stale ZIP is invisible to CI and to review, but `codedapp pack` packs the local build/ directory and Docusaurus fills that from static/ -- so the orphan kept shipping to the deployed site. coding-agents-workshop served a July exercise-1.zip and exercise-2.zip that way until today. Only .zip files are considered, so anything else a repo keeps in static/downloads/ survives. The prune runs before the early exit for an empty downloads/, because an emptied folder is exactly the case where every remaining ZIP is an orphan. It does nothing when downloads/ is absent entirely: the kit is not managing that directory then. The CI test seeds the current ZIP as well as an orphan. Without that, a prune ignoring its keep-set passes unnoticed -- on a fresh tree there is no current ZIP for it to wrongly delete, and generation immediately recreates whatever the prune removed. Mutation-tested against dropping the prune call, ignoring the keep-set, and pruning non-zip files. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Releases the kit as v1.4.0.
package.jsonalready says1.4.0; no tag existed, so no repo could receive any of this.What's here
Shared naming conventions in the agents base (
16329c9) — the conventions now live in the kit'sagents/base.md, soagents buildpropagates them to all five content repos instead of each repo restating them.extract-pptxmoved into the kit (ebf42c3) — two repos had drifting copies ofextract-pptx-assets.py. The deck-specific slide ranges and role keywords became a--slide-mapJSON, so the code is shared and the deck knowledge stays with the workshop.doctornow flags a leftoverscripts/extract-pptx-assets.py. Includes the placeholder-picture fix, regression-tested against a fixture deck whose image sits in a content placeholder.Prune old packages after
codedapp pack(3efdaf9) — keeps 3 per package name..uipath/grew without bound before. Per package name, not globally: one repo packs a different app name per training target, and a global "keep newest N" would destroy an older target's only package.Prune orphaned zips in
static/downloads/(a5a6d2f) — see below.Versioning docs correction (
4dc2ebb) — how consumers actually get a release.Why the ZIP prune matters more than it looks
A deleted
downloads/<name>/folder left its ZIP behind forever, and the failure mode is genuinely invisible:static/downloads/is gitignored, so a stale ZIP is in no commit, no diff, no PR, and CI never sees itcodedapp packpacks the localbuild/directory, and Docusaurus copies all ofstatic/into itcoding-agents-workshopserved a Julyexercise-1.zipandexercise-2.zipthis way for a month. Both are now deleted and the prune stops it recurring in any repo.Behaviour: only
.zipfiles are considered, so anything else a repo keeps instatic/downloads/is untouched. It prunes whendownloads/is emptied — that is exactly the CA shape — but does nothing whendownloads/is absent entirely, since the kit is not managing that directory then.Testing
New
kit-ci.ymlstep, mutation-tested against three mutations: dropping the prune call, ignoring the keep-set, and pruning non-zip files.One subtlety worth recording: the test must seed the current ZIP as well as the orphan. On a fresh tree, a prune that ignores its keep-set is unobservable — there is no current ZIP for it to wrongly delete, and generation immediately recreates anything it removed. The first version of this test passed against that mutation. It now asserts on the log line instead of file existence.
All five content repos were built against this branch and pass with zero anchor warnings.
After merge
Tag
v1.4.0, force-move thev1major tag, thennpx workshop-kit repin v1.4.0in each of the five content repos. Nothing breaks without the repin — the repos are onv1.3.0and these are authoring/deploy-time changes — but the comms-mining README andAGENTS.mdalready name anextract-pptxcommand their pinned kit lacks, and.uipath/keeps growing until it lands.🤖 Generated with Claude Code